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* This source file is subiecc to the terns and conditions of the 

* OLICOM Software License Agreement which restricts the manner 

* in which it may be used. 



* Description; Leaky bucket routines 



$Log: lbuckdt-c.v $ 

Revision 1.3 1998/06/15 12:31:45 ct6 
CreditLef t now returns sdvord rather than sword 

Revision 1.2 199&706/15 11:25:14 cto 
Modifications for process overload buckets , 
Function OseLeakyBueketAf cer added - 

Revision 1.1 1998/06/04 10:43:06 cto 

Addition of leaky bucket files lbucket.c, lbucket.h 



*/ 

static char 
static char 


V I] * -e(#)lbucket-c $Revision: 1.3 5'; 
_v3align(4-sireof (_y_>%4) = (0-sizeof (_V_align) ) 






DESIGN DESCRIPtTQt? 





* This file provides a general-purpose leaky bucket mechanism that can be 

• used for example, to limit the number of events that are handled by a 

- particular process. A leaky bucket is an abstract object that is not 

- directly associated with a queue or any other object in the system. 

- T h e leaky bucket descriptor (of type t_leaky_>ucket> is typically allocated 

* as module* local data. 

* Every leaky bucket has a fill level. When a user uses the bucket, a value 

« is aaded to the fill level. Every t microseconds, the value c is subtracted 

• from the fill level; however, the fill level is never allowed to fall below 

• zero The value t may only take on a fixed set of values, corresponding to 

• the timer hooks available in the system. Typically, these values are 20 ms, 

* 50 ms. 100 as, 1 s, S s, 1 minute, 1 hour, and 1 day; however, 1 day 

• corresponds to 86,400.000,000 us, which cannot be stored in a dword, 

w 

* The bucket sise m is the maximum allowed fill level in the bucket. 

- The difference between the maximum fill level and the current fill level is 

- called the 'credit'. 
•/ 



/ * * ' 

/. TABLE OP CONTENTS "/ 

/ * ' 



/* 

w Callback function for draining the bucket: 

* DrainLeakyBucket 

* API functions: 

* CrcateLeakysucket 
CreditLeft 

« DsstroyLeaky Bucket 

* ModifyLeakyBucket 

* aseLeaky Bucket 
UseLeakyBucketAfter 

*/ 







TXXJODB PIL&S ^ 










fijoclude 

# include 

# include 
* include 


•h_defia*,b' 






private TZPES and nsFUJITIcaiS 








PRIVATE DATA 







/* TED: This must be declared elsewhere: */ 

extern t^hook^event tiaez_20ias - >ooks ; 
extern t^ook^e^eat ti»er_50m* - hooks; 
extem t^ook_eeent ti*exJL00mi - ^xoOks: 
extern t_ho©K_e<rent ti»er_lseOio©ks; 
extern t_boo)i.eveat ci»er,5sec - lioofcs ? 
extern t^hook_eront tiffier_ 1mirU*oota >; 
extern t^booJc^eveat tiaex_Ih6ur Jiookc : 
extern t^hook.eveat tiaer^ldayjiooks ; 



/• TED: This must be »o^ed to eustaa.c: V 
t_tittfir_Jroo)cs aTimerHookB [ 1 



{ fictijaer^OniS-ho 0 ^ 3 ' 

{ & timer ^Onis^ooks . 

{ Aciaer^lOOms^hooks , 

{ tticter^lsec^hooks , 

( fctiaiftr_5s*c.>oo)cs, 

( & c ijner_lhour^hoo)cs , 

( NOIL, 0 } 



= ( 

200000b )- 
S0OO0UL ), 
100000DL ). 
1000000UL ), 
S0000Q0XXL }, 
600O0O0OOL ), 
360OQ0000OOL }, 



* w EXPORTED MSA — — 

*** **** **** 

/*=== a «c= s ====-=*===-==»«^ Drainfceakysucket 

•* Function called by the hook w^^^t^JniA the bucket ^ 

STATIc"void /*RBT Nothing ♦/ 

S2fS2£f* C Address of lea* bucket V 

( c leaky_backet_request *p«VBeq; 

riSkylSicket 'pBucket = (t.leaJc/Jsiickef) bucket; 

cricical_on() : 

if CpBuCket->curxentl-evel < P Bucket->dxainA*ounc> 
pBucket->cuxxentI-evel * 0; 

else 

pBucket->ciirrentL*vel pBucket->dminAmouat; 

ovord reaiwax = pevReq->maxi=:0 ? pBuckec->maxLevel : pe*Reor>**xi , 

Is there now credit enough to service this reque5t? m l 
if Crealaax >= pBucket->currentLev Q l ♦ pevReq->antount) < 
/«• We ha^e enough credit */ 
pBucket->curxcntLevel ♦= p**/Req->aB»ount ; 

(void)gueue_get(&pBucket->evg); /• Fentovc pevRea from queue... «/ 

req^e3t_start(4pevR«a->event^head) ; /* ...and send it V 



else 

break; 

> 

critieal^of £ ( ) ; 



) 

EXTORTED "T 18 ™^ w „„ w . ### „ wW ** w «Z/ 



** Create a leaky bucket. . , , 

« SrarguafflTe must correspond eo one o£ che taer hooks conf xflured 

*» in the system, 



■s createLeaky&ucket — 



S^t^, /*» Address of leaky bucket descriptor V 

/*r« Drain amount every titf "/ 

dword a. 
d» 
( 



t^cw--p«c* ' Drain amount every t us 

T™T ' /*ik Pill level maximum */ 

ct^i t) Time in us between drains V 



t_timer_hooks *pTh; 

/* Find a ti»er book that can handle the time t V 
for (pThmaTimerHooks ; ptfh->hook; pTh++> 
if (pTh->microsec= t ) break; 

if ( ipTh->faook) /* He didn't: find a hook •/ 
return CC_RA£tGt _£RROR ; 

/- initialize the bucket "/ 
pBucket->drain*»ount = c: 
pBuckec->drainTime = c; 
pBucket->maxLevel ■ m; 
psucket->currencL<ev«l = 0; 
pBucket-^pProcess = NULL; 

/* set up the timer hook to handle the bucket V 

pBucket->hook - set_>ook<p»->hook. DiainX^akyBucket. (dword) pBuckec) : 
return CC_0&; 

) 

CreditLeft ==«aw===«i— =~ BK = 
- ^Returns the amount of credit left in the bucket w/ 

sdword" Credit left V 

S££SSck«t -pBucket) /'IN of lea*y bucket descriptor */ 

( return pBucket->maxI<evel - P Bucket->currentLevel ? 

) 

/.=^====« "=™==*= i?estroyteakyBuckec ==*:««=== K =^«^^=="=^ 
** LatrovLeakyBucket prevents the timer from further decreasing the fall 
•* ?etel ^ter^hU function has been called, there will be no external 
« rererencesV^ ^ ^^J^^J^l^ 
laid /*RKt Nothing */ 

Sla^^cteT^lucket) Address of leaky bucket descriptor -/ 

* ASSERT (pBuckec->hooki B MULL. pBucket) ; /* Primitive test that bucket is in use 
^IpBucket^p^oces^NULL. PBuckec) ; /- -^/^~£fore the 

process is dead */ 

clear^hook(*pBucket->hook) ; 

) 



/* , =====MaBS=5 ===== ia .^== ModifyUwOeyBuckec =======-=======-«=~=~=-= a 

--"Modifies the parameters of an existing leaky bucket. The current fill level 
ia the bucket will be left untouched, even if it is greater^than^ ^ 

Return /*RCT Error code V 

t^eaW^tec^p^ucket. Address of leaky bucket descriptor -/ . 

dvord c /-*IN Drain amount every t us V 
dword m, maxiBTaiR V ._ 



dword t) 



/~TK Time in us botw^eft drains •/ 



{ 



t w ti»er_>ook£ *pTh; 
o^ord oldHajctevel; 

ASSERTCpBucket-book'^nUL. Packet) ; /* Primitive test that bucket 13 in use •/ 

/* Find a tiaer hook that can handle the time t V 
tor (pth=aTiaerHooks; pTh->hoofc: pSbr+) 
if (pTOi-fcadcrosecs^x) break; 

if (lpTh->book) /» We didn't find a hook V 
return CC_JlANG3_£RROR ; 

cxitical_on(); 

/* Reinitialize the bucket, but don't couch currtotLerol */ 
oldSaxbevel = p&icket->«ajd-ev*l; 
pBueket->draInAaount c; 
pBucket->drainTijn6 = t; 
pBucket->Jaaott^wel = 

/* Set up the tiaer book to handle the bucket V 

^^!^r^c^Sk->hoo fc . Hrain^eskyBucket. (d-rd.pBucket).- 

/* if the maxLev«l increased, w «y n« be able co service some waitins events 

dvord realltox = pe«*«i->»axi==o ? pBuckec-vaaXI^l : pe»Re<i-»oaxi, 

/• Is there bow credit enough to service this request? -/ 
if (realBax >= pSucket->correntfcevel * pevRefl.-»an»unt> ( 

/■ Ms have enough credit •/ 

patteJcet->curreatfceo«l ♦= pevReei->a«ount: 

(void)<saeue^«t(6 P 8»ctet- J .evQ) : /' ***** PevReq from queue. . - ' 

} 

else 

break: 

> 

) 

critieal_of f ( > ; 
return CC_oK; 



) 



_, [iil tt OscLeakyfiucket a .====.==a»===— 

'-"Gse^ueket increments the fill level on the specified leaky buefcet by the 
« soecified ao^atTlt returns TKOE if the fill level can be incies-nted 
« 3£Z?t£Z5£^ overflowing. If the available credit is less «ta»«mt 
" or if somebody else is waiting for the bucket to dram, the fill level is 
«• not incremented and the function returns FALSE. 

" I« the argument maxi is greater than 0. it specifies a fill level M»»um 
« to bTuseTiStead of the value specified -hen the bucket was ereated. 

the argument pevReq may be SOLL or the address of a user-defined ^ If 

- ™ is iEtNOIiTit is assuaed to be the address of an event In this case 

- L L^t will be returned to the calling process when the desired credit 
. If arable When^Hvtmt is recurned. the fill level has already been 



incremented by the desired aasount. 



/*RET Success? */ 

aw 0 rf amount, / # « J"^^ msxiiam (or 0 for default) V 

t!lSky^bucket.requ eS t -pevReqi /-IS Leaky bucket request event: V 



< 



dword realHax: 

ASSERT (pBucket-»hook ! =NUlX , pBucket) ; /• Primitive test that bucket is in use 
critical_on(> : 

realMax = maxi==Q ? pBuck**t->maxLevel ; maaci; 

/* Test if the bucket will overflow or if somebody is already 
..^^ frv* rhp bucket " / 



) 



if (realHax >° pBucket->curr«ntLerol - amounc &* queue_enpty(fitpBucket->evg) ) ( 
/* No overflow and nobody waiting */ 
p9txcket->CurrancLavttl amount:; 

critical^pff (>; 
return TRUE: 

> 

/* Overflow or samabo&r waiting */ 
if (pcvRetj) { 

pevfteq"*>amount ~ amount ; 

pewR«a-»axi » maxi; t _ 

quaua _put ( *pBucket-;wQ , ft pevSU^><**at^head.re$Ource^^ 

) 

eriticaX_off (): 
return FALSE; 



/• b --_™— mmsss^^^s^ UseLea&BUCkecAfter 

•* This is a special version of OseLeakyBucXec- It is called after tbe 
— resource it monitors has been used- Therefore it newer fails, but it does 



resource it nsuwn ■ - . ■ ~- — — — 

return an indication of whether aa overflow occur ed ox not. 

Xbifi function is primarily intended to be used with process overflow 



bool /*RBT Success? */ 

SettaS^^^^chet. /•» Address of leaky bucket descriptor •/ 

dword amount, Usa * e amount V 

oword maxi) /-IN Alternative mavimrim (or 0 for default) */ 

( 

dword realM&x: 
bool baHoOvvrflov: 

ASSERT(pBucket->hook!»MUIi, pBuctet) ; /* Primitive test caat bueket is in use « 
critical.onO ; 

realnax - maxi=0 ? pBucket->maatfjevel ; maxi: 

pBucket->currentl*evel amount; 

boNoOverf low = (realMax >- pBucket->currentI*!wel) ; 

cricical.off (>i 
return. beNoOverf low; 



oticaw a/s 
Denmark 



JU1 Rights Reserved 

. -nd. conditions of the 

^is source m. is ^«^^^re££^tta 
OLICOM Sotwaxe Incase Mreenent wucu 



in whica it «»y »» « ed - 



- Description: 



Leaky bucket: definitions 



I SSSS^'i-^SSi^- - ^cher than ,~rd 
^^^^^^ 



/ SKLODE FILES .....„-*—.—•——*•/ 

/•-«•»•»"*** 

♦include MCUj»e*SJ» 

, — . sssr»^^™5S!I.- : ' 

v . 

' • v~ *-ew*n a timer nook and the Mae 

• interval it represents. 

tjpedef struct ti^rjjook* ( */ . . 

'"^Lhook.evenc h ^= (tc . ^ corresponding U» » us •/ 

dword «u.crosec. 
> c_ti»er. - hoc<ks; 

._. i _._»w„ 0 ks which contains the 
extern t_ti»er^» i3 used when a process 

d^rd , fill lev^l V 

d*ord maxi * 

c.leaky.bucket is cna leaky bucket descriptor -/ 

typedef struct leaky^uctet ( ^ handling this bucket '/ 

^J»ok . ' ££ln amount e^ery lW 

d^rd draintoount: f tecH(D drains •/ 

*«** r±!^7^»l: /- C«reat fill level */ 




». /« Queue of events that are to b* cent when 

t^qumieji^d evQ; / ^ ia room ia the fi«x=ket V 

* »=oce« ^Process; /♦ Address of process for *icb this backet 
t_proce*s -process, ^ ^ bucket. This field is 

HDLL if this ia not as overload bucket. */ 

) t_leakyjwcket; 

* HCSORTED DATA w^--*****^-* / 

w«***<r— *•••*»«**— *••»-•***»• 



***•****♦-*••*«•'*******• 

.«==rs= cr«ateLea)cytt»c^«t *— «- 

Create a leak/ bucket- fa te configured 

•* The argument t mist correspond to one of trie timer no©«* 

•* ia the system. ^ ^ . ^ - — , */ 

«— - /*R2T Error code V 

f?S^pUt, ****** of lea*, buekflt descriptor •/ 

Cjeaky.bucJcet pBUCjeet, nr^in amount every c us •/ 

<3wor r c ' / * tu pill level fflnyimnn */ 



c ' Fill level 

*j ; /♦o, Tine in us between drains */ 

/.=-« C ===^=-=-— =~« Credits e— 
"Returns the amount of credit ^ e£t ^^f bucket ^ 

loCord / * RET CrediC le£ft V 

t^SScket -pBucket): /'IN ****** of leaky bucket descriptor •/ 



Destroyl-eakyBucket ■== 

'.'^^kyBucKt prev^s the ci^ ^^^^1"' 
»«, t ^ t or this function has been called, there tfin oe no 

I. ff^l^^j^ bu cket, an* the de-scriptor oay be deallocated. _ , 

Coid " " /*RET Kothing */ 

'SS58S3£*S&>«>' Add^s of leaky bucket descriptor V 



::^ieT^ 

- ^e'e^uSet^u be ^^°;^_^iL!LiL!!!!!~-^^^. / 

Tre^ /"HET Brror code -/ 

fteak^tef bucket. /•» Address of ieaxy bucket descriptor V 

I" ^ „ /-IK Brain aaouat every t us "/ 

c ' /-in pill level maxima* •/ 

*j . /«m Time in us between drains */ 



„_ «-—==-■===== UsefceakyBucket ==s«b ========■— = 

noc incremented and the function returns TXLSS. 

Z c ^ argU aent «axi is greater than 0. it specifies e fiU level aaxi^ua 
I; us^nSte^Tof thTvalue specified when the bucket -as created. 

„ w cevsea s*Y be SOU. or the address of a user-defined event. If 

R£E?%£T£ assumed to be the address of « —^f^"-- 
the event will be 



U is not ^uLTr^r^^'^ired cr^, 

is available. «ften Che is returned, the fill level has already been 



incremented by the desired amount. 



bool "~ / WR£T Success? 



UseteafcyBuckett Addr«s o£ leaky bucket descriptor V 

tleaJw-J^ckct -pBucket. 7 ™ 85- 01 " L ^/ 

ZJTlJZZ^Zt- /*IN Usage amount */ 

dwo^a ^at, /-in AlLerTiati , /e naximum (or 0 for default) -/ 



«r *T****4);rV ***** ***** eV<3lt 

"rim—* — - - — —- , 

— This fusctxoa. is pri»"*r _ 

(Jeccecciaii- . _ „ , , — * 

— — ■ * 1 1 /*RgT Success? */ 
S^kyBU.Jce^te^ of ***** descriptor -/ 

t_l«dtf>«** Wrfcei:. TO * 9e ,*°^i« <or 0 for d««*ac> 

dword a»ouat. /wis Alcernatrwe nasuw > 
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